@opentelemetry/core

OpenTelemetry Core

This package provides default implementations of the OpenTelemetry API for trace and metrics. It's intended for use both on the server and in the browser.

Built-in Implementations

• OpenTelemetry Core
  • Built-in Implementations
    • Built-in Propagators
      • W3CTraceContextPropagator Propagator
      • Composite Propagator
      • Baggage Propagator
    • Built-in Sampler
      • AlwaysOn Sampler
      • AlwaysOff Sampler
      • TraceIdRatioBased Sampler
      • ParentBased Sampler
  • Useful links
  • License

Built-in Propagators

W3CTraceContextPropagator Propagator

OpenTelemetry provides a text-based approach to propagate context to remote services using the W3C Trace Context HTTP headers.

const api = require("@opentelemetry/api");
const { W3CTraceContextPropagator } = require("@opentelemetry/core");

/* Set Global Propagator */
api.propagation.setGlobalPropagator(new W3CTraceContextPropagator());

Composite Propagator

Combines multiple propagators into a single propagator.

This is used as a default Propagator

const api = require("@opentelemetry/api");
const { CompositePropagator } = require("@opentelemetry/core");

/* Set Global Propagator */
api.propagation.setGlobalPropagator(new CompositePropagator());

Baggage Propagator

Provides a text-based approach to propagate baggage to remote services using the OpenTelemetry Baggage Propagation HTTP headers.

const api = require("@opentelemetry/api");
const { W3CBaggagePropagator } = require("@opentelemetry/core");

/* Set Global Propagator */
api.propagation.setGlobalPropagator(new W3CBaggagePropagator());

Built-in Sampler

Sampler is used to make decisions on Span sampling.

AlwaysOn Sampler

Samples every trace regardless of upstream sampling decisions.

This is used as a default Sampler

const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { AlwaysOnSampler } = require("@opentelemetry/core");

const tracerProvider = new NodeTracerProvider({
  sampler: new AlwaysOnSampler()
});

AlwaysOff Sampler

Doesn't sample any trace, regardless of upstream sampling decisions.

const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { AlwaysOffSampler } = require("@opentelemetry/core");

const tracerProvider = new NodeTracerProvider({
  sampler: new AlwaysOffSampler()
});

TraceIdRatioBased Sampler

Samples some percentage of traces, calculated deterministically using the trace ID. Any trace that would be sampled at a given percentage will also be sampled at any higher percentage.

The TraceIDRatioSampler may be used with the ParentBasedSampler to respect the sampled flag of an incoming trace.

const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { TraceIdRatioBasedSampler } = require("@opentelemetry/core");

const tracerProvider = new NodeTracerProvider({
  // See details of ParentBasedSampler below
  sampler: new ParentBasedSampler({
    // Trace ID Ratio Sampler accepts a positional argument
    // which represents the percentage of traces which should
    // be sampled.
    root: new TraceIdRatioBasedSampler(0.5)
  });
});

ParentBased Sampler

• This is a composite sampler. ParentBased helps distinguished between the following cases:
  • No parent (root span).
  • Remote parent with sampled flag true
  • Remote parent with sampled flag false
  • Local parent with sampled flag true
  • Local parent with sampled flag false

Required parameters:

• root(Sampler) - Sampler called for spans with no parent (root spans)

Optional parameters:

• remoteParentSampled(Sampler) (default: AlwaysOn)
• remoteParentNotSampled(Sampler) (default: AlwaysOff)
• localParentSampled(Sampler) (default: AlwaysOn)
• localParentNotSampled(Sampler) (default: AlwaysOff)

Parent	parent.isRemote()	parent.isSampled()	Invoke sampler
absent	n/a	n/a	root()
present	true	true	remoteParentSampled()
present	true	false	remoteParentNotSampled()
present	false	true	localParentSampled()
present	false	false	localParentNotSampled()

const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { ParentBasedSampler, AlwaysOffSampler, TraceIdRatioBasedSampler } = require("@opentelemetry/core");

const tracerProvider = new NodeTracerProvider({
  sampler: new ParentBasedSampler({
    // By default, the ParentBasedSampler will respect the parent span's sampling
    // decision. This is configurable by providing a different sampler to use
    // based on the situation. See configuration details above.
    //
    // This will delegate the sampling decision of all root traces (no parent)
    // to the TraceIdRatioBasedSampler.
    // See details of TraceIdRatioBasedSampler above.
    root: new TraceIdRatioBasedSampler(0.5)
  })
});

Useful links

• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
• For help or feedback on this project, join us in GitHub Discussions

License

Apache 2.0 - See LICENSE for more information.